Summary

When composeSubmitHandler validates multiple forms and any are invalid, focus now lands on the field that is visually first in the DOM rather than the first form's first error in array order. This fixes the cross-form gap that surfaces when partners interleave fields from multiple form hooks on the same page.

How it works

A per-form FieldElementRegistry is populated by useField on mount/unmount (via a ref callback added to its existing useForkRef) and read by composeSubmitHandler to sort invalid fields by getBoundingClientRect() and focus the winner directly.

Direct element.focus() bypasses RHF's setFocus, which doesn't reliably resolve refs through react-aria-components (_fields[name]._f.ref ends up as a synthetic placeholder rather than the DOM node).

Two registry-publish paths

The registry is published via context through two complementary paths covering both field-connection modes documented in docs/hooks/hooks.md:

1. Provider-based — SDKFormProvider wraps with FieldElementRegistryProvider.
2. Prop-based — each HookField self-wraps via withFieldElementRegistry using the registry forwarded on the formHookResult prop, so the focus behavior works even when SDKFormProvider is absent.

Errors captured from onInvalid

Reads errors from each form's handleSubmit(onValid, onInvalid) callback rather than formState.errors — the latter is a proxy that returns {} when accessed outside a component subscription.

Hooks aligned

All eight SDK form hooks now construct hookFormInternals via the new useHookFormInternals(formMethods) helper, which attaches the registry instance:

• useEmployeeDetailsForm, useHomeAddressForm, useWorkAddressForm
• useCompensationForm, usePayScheduleForm
• useSignCompanyForm, useSignEmployeeForm
• useFederalTaxesForm (latest hook from feat!: migrate Employee.FederalTaxes to hook architecture and add steady-state edit mode #1670)

Wrapper hooks (useCurrentHomeAddressForm, useCurrentWorkAddressForm) need no changes — they spread the underlying hook's hookFormInternals.

Compatibility with raw UseFormReturn slots

The ComposeSubmitInput union (raw UseFormReturn<T> support added in a recent main commit) is preserved. Raw forms have no registry, so they don't participate in DOM-order sorting and gracefully fall back to RHF's setFocus for their own first error.

Test plan

• New integration test composeSubmitHandler.focus.test.tsx covers both paths:
  • Two SDK hooks composed under SDKFormProvider with interleaved fields → focus lands on the visually first invalid field.
  • Same scenario using formHookResult prop (no SDKFormProvider) → still focuses the visually first invalid field.
• New unit tests in composeSubmitHandler.test.ts cover DOM-order sorting, ties broken by left, fallback when no form publishes a registry, fallback when registry has no entries for the error fields.
• All 2,466 existing tests pass.
• TypeScript: clean.
• Lint: clean (no new warnings).

Made with Cursor